feat: add GitHub Codespaces provider by coygeek · Pull Request #347 · openclaw/crabbox

coygeek · 2026-06-14T07:09:26Z

Closes #348

Summary

Adds a direct GitHub Codespaces SSH lease provider with aliases codespaces and gh-codespaces.

Creates claim-owned GitHub Codespaces via the GitHub REST API and gh authentication.
Uses gh codespace ssh --config to drive normal Crabbox SSH, rsync, run, ssh, status, stop, and cleanup flows.
Adds provider config/flags/env handling, docs, provider metadata, and guarded live-smoke coverage.
Keeps release and cleanup conservative: local claim required, creating login must match, dirty Codespaces fall back to stop/retain, and repo-local config cannot redirect creation to an arbitrary repository.

Verification

go test ./internal/providers/githubcodespaces ./internal/providers/codesandbox ./internal/providers/all ./internal/cli && go test -race ./internal/providers/githubcodespaces ./internal/providers/codesandbox ./internal/providers/all ./internal/cli
node scripts/generate-provider-matrix.mjs --check && node scripts/live-github-codespaces-smoke.test.js && node scripts/live-codesandbox-smoke.test.js && node scripts/live-codesandbox-smoke-classify.test.js && bash scripts/check-docs.sh
cd worker && npm run check && npm test (22 files, 600 tests)
go vet ./... && go build -trimpath -o bin/crabbox ./cmd/crabbox
CRABBOX_LIVE= CRABBOX_LIVE_PROVIDERS= CRABBOX_GITHUB_CODESPACES_SMOKE_REPO= scripts/live-github-codespaces-smoke.sh -> classification=environment_blocked reason=CRABBOX_LIVE_not_enabled
bin/crabbox providers --json assertions for github-codespaces and codesandbox metadata

Live resource creation was not run in this environment because live-provider gates and credentials were intentionally unset. The guarded live-smoke script and its unit tests cover skip, credential, validation, cleanup, and redaction behavior.

Review Notes

Structured review found and the branch fixes:

default warmup retention incorrectly overriding delete-on-release policy;
untrusted repo-local config being able to redirect Codespaces creation.

A final Codex autoreview rerun was blocked by account usage quota, and alternate isolated engines were unavailable or failed before returning structured findings. The branch includes full local verification after the review fixes.

clawsweeper · 2026-06-14T07:10:41Z

Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 8:42 AM ET / 12:42 UTC.

Summary
Adds a built-in github-codespaces SSH lease provider with aliases, config/env/flags, REST and gh lifecycle code, docs, metadata, and guarded live-smoke wiring.

Reproducibility: not applicable. this is a feature PR rather than a bug report. The merge gate is live behavior proof for a new provider lifecycle, not a current-main reproduction path.

Review metrics: 3 noteworthy metrics.

Diff size: 28 files, +4424/-4. This is a broad new provider surface, so live proof and owner review matter more than ordinary unit-test-only validation.
Provider surface: 1 provider added, 2 aliases added. The canonical name and aliases become user-facing compatibility surface once released.
Live proof posted: 0 credentialed branch runs. The PR body and maintainer comments report guarded tests and CI, but no live create/status/run/ssh/release proof yet.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #348
Summary: This PR is the open implementation candidate for the linked GitHub Codespaces provider feature request.

Members:

canonical: Add GitHub Codespaces as a Crabbox Linux provider #348 - The PR body uses closing syntax for the open feature request, and the issue body describes the same Phase 1 GitHub Codespaces provider contract.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P1] Add redacted terminal output, logs, or a recording of a live credentialed Codespaces smoke on the current head; redact tokens, private endpoints, repo secrets, and personal details.
After proof is added, update the PR body so ClawSweeper re-reviews automatically, or ask a maintainer to comment @clawsweeper re-review.

Proof guidance:

[P1] Needs real behavior proof before merge: The PR has tests, CI notes, and guarded smoke coverage, but no redacted live Codespaces create/status/run/ssh/release proof on the current branch. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

[P1] No redacted live run has been posted for real GitHub Codespaces create, status --wait, run, SSH command generation, stop/release, and cleanup on the current head.
[P1] Merging adds a billable direct-cloud provider that uses the operator's GitHub CLI or token auth to create, stop, and delete remote resources, so repo selection, identity, and cleanup boundaries need maintainer acceptance.
[P1] The new provider name, aliases, config keys, env vars, default machine, work-root behavior, and delete/retain release policy become compatibility surface once released.

Maintainer options:

Require Live Codespaces Proof (recommended)
Ask for redacted terminal output, logs, or a recording showing live doctor, create/warmup, status --wait, run, ssh command generation, stop/release, and cleanup on the current head before merge.
Accept The Provider Contract
Maintainers can explicitly accept the provider name, aliases, config/env surface, direct gh auth model, and default release behavior after reviewing the tradeoffs.
Pause Until Sponsored
If live quota or product ownership is not available, pause this PR and keep Add GitHub Codespaces as a Crabbox Linux provider #348 open as the canonical feature request.

Next step before merge

[P1] Human review is needed because the remaining blockers are live-provider proof and maintainer acceptance, not a narrow automated code repair.

Security
Cleared: No concrete line-level security or supply-chain defect was found, but the new auth and remote-resource boundary still needs live proof and maintainer acceptance before merge.

Review details

Best possible solution:

Land only after redacted live provider proof confirms the full lifecycle and maintainers accept the built-in provider contract and defaults.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR rather than a bug report. The merge gate is live behavior proof for a new provider lifecycle, not a current-main reproduction path.

Is this the best way to solve the issue?

Unclear until live proof is posted: the adapter shape matches the provider architecture and includes useful guardrails, but unit fakes and guarded smoke tests do not prove the real Codespaces SSH/API lifecycle.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 73549f35a4a0.

Label changes

Label justifications:

P2: This is a normal-priority provider feature with limited blast radius but meaningful merge-readiness requirements.
merge-risk: 🚨 auth-provider: The provider uses the operator's GitHub CLI or token auth to create and manage Codespaces resources.
merge-risk: 🚨 compatibility: The provider name, aliases, config keys, defaults, and release behavior become compatibility surface after merge.
merge-risk: 🚨 security-boundary: The diff adds a new remote execution provider with auth, repo selection, local claims, and destructive cleanup boundaries.
rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR has tests, CI notes, and guarded smoke coverage, but no redacted live Codespaces create/status/run/ssh/release proof on the current branch. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

Repository policy read: AGENTS.md was read fully and applied to provider boundary, neutral example, and secret-handling review. (AGENTS.md:1, 73549f35a4a0)
Current main lacks this provider: Current main has no github-codespaces, githubcodespaces, or gh-codespaces implementation/docs hits, so the PR is not obsolete on main. (73549f35a4a0)
Latest release lacks this provider: The latest release tag v0.33.0 also has no Codespaces provider registration/config/docs hits in the checked surfaces. (966e99599db4)
Provider registration surface: The PR registers canonical provider github-codespaces, aliases codespaces and gh-codespaces, Linux SSH lease features, and direct-only coordinator behavior. (internal/providers/githubcodespaces/provider.go:21, 2eb4f8afe67f)
Auth and cleanup guardrails: The lifecycle code requires a local claim for release, validates the GitHub login, and falls back to stop/retain instead of deleting dirty Codespaces. (internal/providers/githubcodespaces/backend.go:299, 2eb4f8afe67f)
Untrusted config guardrails: Repo-local config cannot change the API URL, gh executable path, or target repository; only trusted config/env/flags can set those routing controls. (internal/cli/config.go:4416, 2eb4f8afe67f)

Likely related people:

coygeek: Current main history shows this contributor added adjacent provider foundations and metadata/docs patterns used by this PR, including CodeSandbox, Lambda, and Firecracker provider work. (role: adjacent provider contributor; confidence: high; commits: 460e241d1b71, 6e7939dbdc63, 3f72d94e2ae7; files: internal/providers/all/all.go, internal/cli/config.go, docs/providers/provider-metadata.json)
vincentkoc: Recent current-main live-smoke dispatch history and PR comments show direct involvement in provider smoke wiring, rebases, CI validation, and proof gating for this branch. (role: recent area contributor and reviewer; confidence: high; commits: 56d058c0b846, 2eb4f8afe67f; files: scripts/live-smoke.sh, scripts/live-smoke.test.js, docs/operations.md)
steipete: The latest merged AWS Lambda MicroVM provider commit touched the same built-in provider registry, config, docs, and smoke-test surface adjacent to this provider expansion. (role: adjacent provider contributor; confidence: medium; commits: 0301236b2752; files: internal/cli/config.go, internal/providers/all/all.go, docs/providers/README.md)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

vincentkoc · 2026-06-24T05:48:58Z

@clawsweeper re-review

Maintainer update on 2afc239e021e093fd021e2b09657d7831e7cb0ba:

rebased the GitHub Codespaces provider branch onto current main
fixed the CI Go/deadcode failure by removing unreachable helper wrappers from internal/providers/githubcodespaces/core.go
regenerated the provider category matrix so the generated docs check stays in sync

Local validation:

go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox

GitHub CI on the pushed head is green: Go, Apple VZ, Worker, Scripts, Docs, and Release Check all passed in https://github.com/openclaw/crabbox/actions/runs/28077485642.

Still not merging this yet: it remains gated by status: 📣 needs proof, merge-risk: 🚨 auth-provider, merge-risk: 🚨 compatibility, and merge-risk: 🚨 security-boundary. I do not have live GitHub Codespaces provider credentials/quota proof here, so this still needs real live create/status/run/ssh/release evidence before merge readiness.

clawsweeper · 2026-06-24T05:49:01Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Add the discoverable github-codespaces provider foundation with typed config, provider flags, redaction-safe client and gh runner boundaries, and OpenSSH config parsing for the future SSH lease lifecycle. Keep live Codespaces lifecycle behavior intentionally deferred to the next plan while making doctor fail closed until readiness is implemented.

Add claim-backed acquire, resolve, list, release, touch, cleanup, and doctor behavior for GitHub Codespaces, including generated OpenSSH config targets and conservative delete safety checks. Release and cleanup mutations now require local ownership claims, refuse dirty or unpushed codespaces before delete, and keep retained lease labels/endpoints consistent across stop and wake flows. Verification: go test ./internal/providers/githubcodespaces; go test -race ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli

Document the direct GitHub Codespaces provider, add generated matrix metadata, and add a guarded live smoke with deterministic gating/redaction tests.

Align the GitHub Codespaces backend with the documented default cleanup policy, GitHub CLI token precedence, bounded provisioning waits, explicit generic work root handling, and the real gh SSH config Host alias shape.

Validate that the guarded GitHub Codespaces smoke lease is absent after cleanup without failing on unrelated retained claim-owned Codespaces leases.

Persist the effective Codespaces work root into lease labels and claims, and rewrite generated gh SSH proxy commands to honor the configured GitHub CLI path.

Keep GitHub Codespaces display names within the documented limit for long but valid Crabbox slugs while preserving the collision-resistant suffix. Also assert that create requests continue using the current geo field rather than the legacy location field.

Fall back to stopping and retaining a Codespace when default delete-on-release is unsafe because the remote worktree has uncommitted or unpushed changes. This avoids turning successful runs into failed cleanup while still clearing stale SSH endpoints.

Make the release-claim retention hook read the post-release claim state so dirty Codespaces that fall back from delete to stop are not orphaned by higher-level release finalizers.

Treat GitHub Codespaces 304 Not Modified start responses as successful no-ops so resolving retained Codespaces can continue polling the existing codespace.

Apply the generic --type machine override for the canonical provider and advertised Codespaces aliases so alias-based invocations do not silently provision the default machine size.

Treat GitHub Codespaces 304 Not Modified delete responses as successful no-ops so release and cleanup remain idempotent when GitHub reports no remote state change is needed.

Allow StatusOnly resolves with ReadyProbe to refresh and probe the SSH target so status --wait can observe readiness for healthy Codespaces leases.

Warmup keep semantics should keep a lease available after provisioning, not rewrite the later provider release action. Preserve the delete-on-release policy in stored Codespaces claims so default stop and cleanup paths delete claim-owned Codespaces unless configuration explicitly retains them.

Treat githubCodespaces.repo like the other Codespaces connection selectors when loading untrusted repository config. Repo-local config can no longer redirect creation to an arbitrary repository; operators can still select a repo through trusted config, environment, or explicit CLI flags.

vincentkoc · 2026-06-24T08:58:28Z

Rebased this PR onto current main after #674 landed.

New head: 41ccc44ed02061a53eb20a55a848ed18aa91f352

Conflict resolution kept both AWS Lambda MicroVM and GitHub Codespaces in generated docs/source-map metadata. Provider matrix now reports 67 providers.

Local validation on the rebased head:

go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node --test scripts/live-github-codespaces-smoke.test.js
node scripts/generate-provider-matrix.mjs --check
node scripts/check-command-docs.mjs
node scripts/check-docs-links.mjs
go vet ./...
go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
go build -trimpath -o bin/crabbox ./cmd/crabbox
git diff --check

Still not merging: live GitHub Codespaces create/status/run/ssh/release proof and auth/security/compatibility gates are still required.

vincentkoc · 2026-06-24T09:15:57Z

Public CI is green on rebased head 41ccc44ed02061a53eb20a55a848ed18aa91f352: https://github.com/openclaw/crabbox/actions/runs/28087205563

Green checks: Go, Apple VZ, Worker, Scripts, Docs, and Release Check. Merge state is clean.

Still not merging: status: 📣 needs proof plus auth-provider/compatibility/security-boundary labels remain, and this still needs redacted live GitHub Codespaces create/status/run/ssh/release proof.

vincentkoc · 2026-06-24T12:31:34Z

Maintainer proof update for github-codespaces shared live-smoke wiring.

Changed:

wired CRABBOX_LIVE_PROVIDERS=github-codespaces|codespaces|gh-codespaces through scripts/live-smoke.sh to the guarded standalone Codespaces smoke
added shared dispatch regression coverage that proves the shared smoke exits before provider mutation when the smoke repo is missing
documented the shared operations entry point and provider prerequisites

Local validation at head 2eb4f8af:

bash -n scripts/live-smoke.sh scripts/live-github-codespaces-smoke.sh
node --test scripts/live-smoke.test.js scripts/live-github-codespaces-smoke.test.js
go test ./internal/providers/githubcodespaces ./internal/providers/all ./internal/cli ./cmd/crabbox
node scripts/check-docs-links.mjs
node scripts/check-command-docs.mjs
git diff --check

Still not claiming live provider proof from this machine because I do not have an authenticated Codespaces smoke repo/token here. The added path is meant to make that live proof one standard command once credentials are available.

@clawsweeper re-review

clawsweeper · 2026-06-24T12:31:37Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

coygeek marked this pull request as ready for review June 14, 2026 07:10

coygeek mentioned this pull request Jun 14, 2026

Add GitHub Codespaces as a Crabbox Linux provider #348

Open

vincentkoc force-pushed the feat/github-codespaces-provider branch from 1887b52 to 2afc239 Compare June 24, 2026 05:32

coygeek and others added 17 commits June 24, 2026 16:55

docs(github-codespaces): add docs and live smoke

f7bacc2

Document the direct GitHub Codespaces provider, add generated matrix metadata, and add a guarded live smoke with deterministic gating/redaction tests.

fix(github-codespaces): harden lifecycle defaults

6b3ef39

Align the GitHub Codespaces backend with the documented default cleanup policy, GitHub CLI token precedence, bounded provisioning waits, explicit generic work root handling, and the real gh SSH config Host alias shape.

fix(github-codespaces): scope live smoke cleanup check

396cde2

Validate that the guarded GitHub Codespaces smoke lease is absent after cleanup without failing on unrelated retained claim-owned Codespaces leases.

fix(github-codespaces): propagate runtime SSH config

5c360cc

Persist the effective Codespaces work root into lease labels and claims, and rewrite generated gh SSH proxy commands to honor the configured GitHub CLI path.

fix(github-codespaces): retain fallback claims

770fcf4

Make the release-claim retention hook read the post-release claim state so dirty Codespaces that fall back from delete to stop are not orphaned by higher-level release finalizers.

fix(github-codespaces): accept start no-op

ac78d5c

Treat GitHub Codespaces 304 Not Modified start responses as successful no-ops so resolving retained Codespaces can continue polling the existing codespace.

fix(github-codespaces): honor type aliases

dc19d36

Apply the generic --type machine override for the canonical provider and advertised Codespaces aliases so alias-based invocations do not silently provision the default machine size.

fix(github-codespaces): accept delete no-op

e600d1a

Treat GitHub Codespaces 304 Not Modified delete responses as successful no-ops so release and cleanup remain idempotent when GitHub reports no remote state change is needed.

fix(github-codespaces): probe status waits

8044b5d

Allow StatusOnly resolves with ReadyProbe to refresh and probe the SSH target so status --wait can observe readiness for healthy Codespaces leases.

fix(github-codespaces): remove unused helper wrappers

ee77a65

docs(github-codespaces): refresh provider category matrix

41ccc44

vincentkoc force-pushed the feat/github-codespaces-provider branch from 2afc239 to 41ccc44 Compare June 24, 2026 08:58

test(github-codespaces): wire shared live smoke

2eb4f8a

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add GitHub Codespaces provider#347

feat: add GitHub Codespaces provider#347
coygeek wants to merge 18 commits into
openclaw:mainfrom
coygeek:feat/github-codespaces-provider

coygeek commented Jun 14, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 14, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

coygeek commented Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Review Notes

Uh oh!

clawsweeper Bot commented Jun 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

vincentkoc commented Jun 24, 2026

Uh oh!

clawsweeper Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coygeek commented Jun 14, 2026 •

edited

Loading

clawsweeper Bot commented Jun 14, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading

clawsweeper Bot commented Jun 24, 2026 •

edited

Loading